C!T ROM 3

home *** CD-ROM | disk | FTP | other *** search

/ C!T ROM 3 / ct-rom iiib.zip / ct-rom iiib / WINDOWS / DIVERSEN / CBOOK110 / README.TXT < prev next >

Wrap

Text File | 1993-09-21 | 12KB | 352 lines

How to create your own cookbooks | | (c) Andrew Brown, September 1993 | ---------------------------------+ INTRODUCTION ------------ Cookbook Manager for Windows v1.10 introduced a feature that allows users to create their own cookbooks for viewing with Cookbook Manager. This document describes how to use the MAKEBOOK program. Please note that MAKEBOOK is a DOS utility, not a Windows program -- although it works quite happily in a Windows DOS session. BEFORE YOU START ---------------- Before you attempt to create your own cookbook, there is one initialisation step that you should perform. In the MAKEBOOK directory, you will find a program file called MAKEBOOK.EXE. This file should be copied to a directory contained within your PATH environment variable, such as \DOS. The reason for this step is that you will be working on your new cookbook in a sub-directory created especially for that purpose, and you will want instant access to the MAKEBOOK.EXE program. A STEP BY STEP GUIDE TO CREATING A COOKBOOK ------------------------------------------- 1. Create a directory somewhere on your hard disk for the express purpose of working on this cookbook. 2. Use a text editor to create the recipe files that constitute your cookbook. 3. Run the MAKEBOOK.EXE program. 4. If errors are reported, correct them and return to step (3) 5. Copy the newly created .DEF and .DAT files to the BOOKS directory. THOSE STEPS IN MORE DETAIL -------------------------- 1. Creating a directory ----------------------- Since the MAKEBOOK program will operate on every recipe file that it finds in the current directory, it is good housekeeping practice to create a sub-directory for every cookbook that you create. A sensible directory structure might look like this: COOKBOOKS | +--INDIAN | +--CHINESE | +--THAI This shows a parent directory called COOKBOOKS, with sub-directories called INDIAN, CHINESE and THAI. Each of these three sub-directories will contain the recipe files that constitute that cookbook. The MS-DOS command "MD" can be used to create sub-directories. 2. USING A TEXT EDITOR TO CREATE RECIPE FILES --------------------------------------------- Every recipe in your cookbook is descibed in its own file. These files are simple ASCII text files that can be created and edited using any ASCII text editor, such as the MS-DOS "edit" command. Each recipe file can have any name that you like, but MUST have an extension of ".REC". The recipe files must be formatted in a special way so that MAKEBOOK can make sense of them. See Appendix (A) for a full description of the format of a recipe file. If you were creating a cookbook for Indian recipes, you might have the following recipe files, perhaps contained in a sub-directory called "INDIAN" (see step (1) above). MADRAS.REC VINDALOO.REC BHUNA.REC TIKKA.REC RJOSH.REC etc... 3. RUNNING THE MAKEBOOK.EXE PROGRAM ----------------------------------- When you have created the recipes that constitute your cookbook, you should run the MAKEBOOK program in order to create the cookbook itself. The syntax of MAKEBOOK is: MAKEBOOK bookname Where "bookname" is the filename of the cookbook that you want to create. DO NOT supply a file extension for the cookbook -- MAKEBOOK needs to add its own. If all goes OK then you should see various progress messages appear on the screen, followed by a request to enter the name of the cookbook. This is the name that will appear in the "Select cookbook" menu of Cookbook Manager. Please don't enter a name that is too long, otherwise it will look ugly inside the menu. 20 characters should be considered a maximum. 4. WHAT TO DO IN THE CASE OF AN ERROR ------------------------------------- MAKEBOOK will add every .REC file in the current directory to the cookbook. If an error is encountered during processing then a message will be printed and MAKEBOOK will abort and return you to the DOS prompt. You should then attempt to fix the error and re-run MAKEBOOK. Appendix (B) lists all the errors that MAKEBOOK can produce. 5. COPYING THE .DEF AND .DAT FILES ---------------------------------- The final result of running MAKEBOOK is that two new files are created in the current directory. They have the extensions of ".DAT" and ".DEF". The DAT file is the cookbook itself, whilst the .DEF file is a text file that contains the cookbook details. You should use the DOS "copy" command (or the Windows File Manager if you're that way inclined) to copy these files to the BOOKS directory. In case you were unsure, the BOOKS directory can be found within the directory that contains the COOKBOOK.EXE file. When you run Cookbook Manager, it searches this directory for cookbooks and adds their names to the "Select cookbook" menu. APPENDIX A. THE FORMAT OF A RECIPE FILE --------------------------------------- Each recipe file that you create MUST start in the following manner: .TYPE recipe type code .TITLE short recipe title .SHORTDESC one line recipe description multi-line description of recipe, giving background, introduction etc. This section can consist of as many paragraphs as you like, and is optional. Only the one-line description is mandatory. .TYPE ----- The .TYPE command must be followed by a recipe code that tells Cookbook Manager what type of recipe this is, and whether or not it is suitable for vegetarians. This code must appear on its own line, and should be in upper case text. The possible codes are: M Main dish A Appetizer B Bread L Beverage C Cookie SL Salad SP Soup S Sauce D Dessert O Other Each of the above codes may have a "V" suffix to indicate that the recipe is suitable for vegetarians. Some examples are: MV Main dish, suitable for vegetarians SL Salad, not suitable for vegetarians SPV Soup, suitable for vegetarians .TITLE ------ Every recipe has a title, and it should follow this command on its own line. The recipe title must NOT contain spaces, where spaces are desired it is traditional to use the minus sign ("-") instead. This is the title that will appear in the Cookbook Manager search dialogue box. .SHORTDESC ---------- This command should be followed by a one-line short description of the recipe. This one line description may be followed by as many paragraphs of recipe description as you like. These paragraphs are not mandatory, but it is traditional and indeed desirable to provide your reader with some background to the recipe. THE REST OF THE RECIPE FILE --------------------------- The rest of the recipe file can just consist of ordinary paragraphs of text that describe its various aspects. Wherever you want a header, you should start the line with a period ("."), for example: .INGREDIENTS is a very common header ! If you want some italic text then you should enclose it in the \IT{text} command. For example: This is \IT{italic} text would produce the word "italic" in italicised text. You cannot have italic text that runs over more than one line. There are two sections that are present in almost every recipe, these are the ingredients and procedure sections. For that reason there are several commands that you can use to aid in their constructions. THE INGREDIENTS SECTION ----------------------- When viewed in Cookbook Manager, an ingredients section might look like this: 1 pint Milk (full cream) 2 eggs In the recipe file, you should write this as: 1 pint{IG}Milk (full cream) 2{IG}eggs The {IG} command is an instruction to insert a reasonable amount of space and to format the rest of the line in italics. This produces a pleasant on-screen format. THE PROCEDURE SECTION --------------------- You might choose to write your procedure as one or more paragraphs of descriptive text, this is fine -- a lot of recipes are formatted this way. However, you might like to itemise each procedure step with a number. If so, this is how you set it out: {1} This is step one. Write as many paragraphs as you like. {2} This is step two. {3} This is step three. The {n} commands instruct Cookbook Manager to indent the following paragraphs so that they look pleasant on-screen. RECOMMENDED FORMAT ------------------ After the mandatory start to every recipe file, you can include whatever information you like. However, it is recommended that you include at least the following sections in your recipe file so that future versions of Cookbook Manager might make use of them. INGREDIENTS - Cookbook Manager looks for this when searching for ingredients PROCEDURE - Cookbook Manager considers this header as the end of the ingredients section. NOTES - Not yet used, but recommended for inclusion. CONTRIBUTOR - Not yet used, but recommended for inclusion. APPENDIX B. ERROR MESSAGES -------------------------- Cannot create cookbook the .DAT file could not be created. Make sure that the filename you gave as a parameter to MAKEBOOK is valid, and does not have an extension. Cannot open recipe file A .REC file was found, but could not be opened for reading. Check the file and disk structure, this is an error that should not occur. No recipe files found No .REC files were found in the current directory. Cannot create temporary file MAKEBOOK needs to use a temporary file, if it could not create one then you get this message. Is your disk write protected ? .TYPE code text is the wrong size You get this error if the line following the .TYPE command contains more than 3 characters of text (the maximum length of a recipe type code). recipe title cannot contain spaces The single line that follows the .TITLE command cannot contain any space characters. .SHORTDESC encountered before .TYPE .SHORTDESC encountered before .TITLE mandatory section not present or incomplete The recipe file does not conform to the mandatory section described in Appendix (A). '}' missing (must be on same line as '{') \IT{text} command does not have a closing }. The closing } must appear on the same line as the {. cannot re-open temporary file Very strange error that indicates that the temporary file was created OK but could not be re-opened for reading. You should never see this error. read failed on temporary file The temporary file could be opened OK but then reading it failed. You should never see this error. file write error Fairly generic error that can occur during any write operation. The reason might be that your disk is full. cannot create .DEF file The .DEF file could not be opened for writing. You should not see this error since its cause is likely to be caught by the "cannot open cookbook" error, that appears earlier in the execution cycle. APPENDIX C. EXAMPLES -------------------- The EXAMPLES directory contains five example recipe files, taken from "The Cat's Meow" on-line beer-brewing guide. The ".REC" files should give you a good idea how to create recipe files. If you so wish, you can use MAKEBOOK in the example directory to create a new cookbook for viewing with Cookbook Manager. FINALLY ------- There are many on-line collections of recipes available in ASCII format. Usually these are of a fairly regular structure. Anyone out there with a degree in Perl or Awk should be able to knock up an automatic recipe file creator -- any takers ? Bon Appetite, Andy Brown (asb@cs.nott.ac.uk) E-mail address expires in July 1994 -- do not use after this date.